home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacApp Release 10 / MacApp Release 10 - HD Ready / Libraries / Framework / Includes / UScriptableObject.h < prev    next >
Encoding:
Text File  |  1996-04-03  |  11.7 KB  |  318 lines  |  [TEXT/MPS ]
  1. // UScriptableObject.h
  2. // Copyright © 1984-96 by Apple Computer, Inc. All rights reserved.
  3.  
  4. #ifndef __USCRIPTABLEOBJECT__
  5. #define __USCRIPTABLEOBJECT__
  6.  
  7. // MacApp
  8.  
  9. #ifndef __MACAPPTYPES__
  10. #include "MacAppTypes.h"
  11. #endif
  12.  
  13. #ifndef __UCLASSDESC__
  14. #include "UClassDesc.h"
  15. #endif
  16.  
  17. // Toolbox
  18.  
  19. #ifndef __OSA__
  20. #include <OSA.h>
  21. #endif
  22.  
  23. #if qAttachable
  24.     #ifndef __UOSASCRIPT__
  25.     #include "UOSAScript.h"
  26.     #endif
  27. #endif
  28.  
  29.  
  30. //----------------------------------------------------------------------------------------
  31. // Forward and external class declarations. 
  32. //----------------------------------------------------------------------------------------
  33.  
  34. class CAEDesc;
  35. class TAppleEvent;
  36. class TCommandHandler;
  37. class TScriptableObjectList;
  38. class TStream;
  39.  
  40. //----------------------------------------------------------------------------------------
  41. // MScriptableObject: Definition of an object that responds to scripting appleevents.
  42. //----------------------------------------------------------------------------------------
  43.  
  44. const long kAllProperties = -1; // Constant to get all properties when calling MScriptableObject:GetContents
  45.  
  46. class MScriptableObject
  47. {
  48.     MA_DECLARE_CLASS;
  49.     
  50.   public:
  51.     DescType         fOMClassID;            // The object model class id.
  52. #if qAttachable
  53.     COSAScriptCntPtr    fOSAScript;
  54. #endif
  55.  
  56. //----------------------------------------------------------------------------------------
  57. // Construction
  58. //----------------------------------------------------------------------------------------
  59. public:
  60.     MScriptableObject();
  61.     MScriptableObject(DescType myClassID);
  62.  
  63. #if qAttachable
  64.     virtual ~MScriptableObject();
  65. #endif
  66.  
  67. //----------------------------------------------------------------------------------------
  68. // Object Description
  69. //----------------------------------------------------------------------------------------
  70.  
  71.     virtual DescType GetOMClass();
  72.     // Override this to return something other than fOMClassID for the AppleEvent Object
  73.     // Model class for this object.
  74.     
  75.     virtual DescType GetSpecifierForm();
  76.     // Override this to return something other than formIndex.
  77.  
  78.     virtual Boolean MakeObjectSpecifier(CAEDesc& theObjectSpecifier,
  79.                                         DescType preferredForm);
  80.     // Creates an object specifier describing this object. This calls GetObjectProperty and
  81.     // GetContainer to support formName, formAbsolutePosition, and formUniqueID.
  82.     // You'll only need to override this method if you want to make other forms of
  83.     // object specifiers.
  84.  
  85. //----------------------------------------------------------------------------------------
  86. // Accessing Contained Objects
  87. //----------------------------------------------------------------------------------------
  88.  
  89.     virtual MScriptableObject* GetIndContainedObject(DescType desiredType,
  90.                                                      long index);
  91.     // Returns an object contained within this one based on its absolute
  92.     // position within the container. If you override this method to return
  93.     // contained objects TObject::GetContainedObject will use this to get
  94.     // one or more objects required by the different reference forms.
  95.  
  96.     virtual MScriptableObject* GetObjectsWithinRange(DescType desiredType,
  97.                                                      MScriptableObject* startBounds,
  98.                                                      MScriptableObject* endBounds);
  99.     // Returns an object or list of objects contained within this one
  100.     // that lie within the startBounds object and the endBounds object.
  101.     // The default method assumes that the startBounds and endBounds objects
  102.     // are of the desiredType.
  103.     // You can override this to provide custom range access.
  104.  
  105.     virtual MScriptableObject* GetAdjacentObject(DescType desiredType,
  106.                                                  DescType position);
  107.     // When the OSL resolves relative reference forms it first specifies an object
  108.     // then asks that object for the one before or after it. This method returns
  109.     // an object of the desiredType before or after it. The default implementation
  110.     // does this by calling GetIndContainedObject for its container until it
  111.     // finds itself, the gets the adjacent object by index. This only works if the
  112.     // desiredType is the same as this object.
  113.     // You can override this method by to provide custom access.
  114.  
  115.     virtual MScriptableObject* GetContainedObject(DescType desiredType,
  116.                                                   DescType selectionForm,
  117.                                                   const CAEDesc& selectionData);
  118.     // Returns an object contained within this one. If the desiredType is a property
  119.     // of this object, we create a TPropertyAccessor and return it.
  120.     // Later on, the TPropertyAccessor can act on the properties of this object.
  121.  
  122.     virtual MScriptableObject* GetObjectsContainer();
  123.     // Returns the object that contains this one.
  124.  
  125.     virtual long CountContainedObjects(DescType desiredType);
  126.     // Override this to return a count of the number of objects contained within this one.
  127.  
  128.     virtual TScriptableObjectList* MakeNewMarkingList();
  129.     // Returns a TScriptableObjectList to use for marking objects contained within this one. 
  130.  
  131. //----------------------------------------------------------------------------------------
  132. // Comparison
  133. //----------------------------------------------------------------------------------------
  134.  
  135.     virtual Boolean CompareScriptableObjects(DescType operation,
  136.                                              const CAEDesc& thingToCompare);
  137.     // Compares this object to something else. The default method does a simple
  138.     // direct comparison.
  139.  
  140.     virtual Boolean CompareProperties(DescType whichProperty,
  141.                                       DescType operation,
  142.                                       const CAEDesc& thingToCompare);
  143.     // Compares a property of this object to something else.
  144.  
  145. //----------------------------------------------------------------------------------------
  146. // Handling AppleEvents
  147. //----------------------------------------------------------------------------------------
  148.     
  149.     virtual void DoAEOnContainedObjects(TScriptableObjectList* theObjectList,
  150.                                         CommandNumber aCommandNumber,
  151.                                         TAppleEvent* message,
  152.                                         TAppleEvent* reply);
  153.     // If a complex object specifier resolves into a group of objects, the object
  154.     // containing them gets a chance to handle the AppleEvent for the group.
  155.     // The default method handles the SetData event by creating a command to 
  156.     // change the properties of all the objects.
  157.     
  158.     virtual TCommandHandler* GetCommandContext(const CommandNumber aCommandNumber) const;
  159.  
  160. #if qOptimizeSelfSendAevt    
  161.     
  162.     virtual Boolean IsPendingAction(const CommandNumber aCommandNumber, 
  163.                                     const unsigned long actionID) const;
  164. #endif
  165.     
  166.     void HandleScriptCommand(CommandNumber    aCommandNumber,
  167.                             TAppleEvent*     message,
  168.                             TAppleEvent*     reply);
  169.     // Behaviors attached to the target object are given a chance to handle the event.
  170.     // If the event is not handled by a behavior, DoScriptCommand is called.                                
  171.                                                 
  172.     virtual void DoScriptCommand(CommandNumber    aCommandNumber,
  173.                                 TAppleEvent*     message,
  174.                                 TAppleEvent*     reply);
  175.     // Aftering resolving an object specifier into an object this method is called.
  176.     // Based on the command number in the aCommandNumber it dispatches the event to
  177.     // one of the Core event support routines defined below.
  178.     // Override this method if this object supports events beyond the core suite.
  179.     
  180.     // Methods called for the core suite events.
  181.  
  182.     virtual void DoAEClone(TAppleEvent* message, TAppleEvent* reply);
  183.                                 
  184.     virtual void DoAEClose(TAppleEvent* message, TAppleEvent* reply);
  185.  
  186.     virtual void DoAECountElements(TAppleEvent* message, TAppleEvent* reply);
  187.                                 
  188.     virtual void DoAECreateElement(TAppleEvent* message, TAppleEvent* reply);
  189.                                 
  190.     virtual void DoAEDelete(TAppleEvent* message, TAppleEvent* reply);
  191.                                 
  192.     virtual void DoAEDoObjectsExist(TAppleEvent* message, TAppleEvent* reply);
  193.                                 
  194.     virtual void DoAEGetClassInfo(TAppleEvent* message, TAppleEvent* reply);
  195.                                 
  196.     virtual void DoAEGetEventInfo(TAppleEvent* message, TAppleEvent* reply);
  197.                                 
  198.     virtual void DoAEGetData(TAppleEvent* message, TAppleEvent* reply);
  199.                                 
  200.     virtual void DoAEGetDataSize(TAppleEvent* message, TAppleEvent* reply);
  201.                                 
  202.     virtual void DoAEMove(TAppleEvent* message, TAppleEvent* reply);
  203.  
  204.     virtual void DoAEOpen(TAppleEvent* message, TAppleEvent* reply);
  205.  
  206.     virtual void DoAEPrint(TAppleEvent* message, TAppleEvent* reply);
  207.  
  208.     virtual void DoAESave(TAppleEvent* message, TAppleEvent* reply);
  209.                                 
  210.     virtual void DoAESetData(TAppleEvent* message, TAppleEvent* reply);
  211.  
  212. //----------------------------------------------------------------------------------------
  213. // Object Properties
  214. //----------------------------------------------------------------------------------------
  215.                                 
  216.     virtual Boolean GetContents(CAEDesc& theContents, const CAEDesc& desiredType,
  217.                                 long propertyFlags = kAllProperties);
  218.     // Returns the contents of this object.
  219.  
  220.     virtual void SetContents(const CAEDesc& theContents);
  221.     // Sets the contents of this object. If theContents is an AERecord,
  222.     // SetObjectProperty will be called for each property key.
  223.     
  224.     virtual Boolean GetObjectProperty(CAEDesc& thePropertyValue,
  225.                                          DescType whichProperty,
  226.                                       const CAEDesc& desiredType);
  227.     // Gets property values for this object.  Returns true if the property was available,
  228.     // false if not.
  229.                                 
  230.     virtual void SetObjectProperty(const CAEDesc& thePropertyValue,
  231.                                    DescType whichProperty);
  232.     // Override this method to set property values for this object.
  233.  
  234.     virtual void GetSetPropertyInfo(DescType whichProperty,
  235.                                     CommandNumber& aCommandNumber,
  236.                                     Boolean& canUndo,
  237.                                     Boolean& causesChange,
  238.                                     TCommandHandler* &theContext);
  239.     // When an AppleEvent is received that will set a property for this object a TSetPropertyCommand
  240.     // will be created to do it. You can override this method to provide the command number and the
  241.     // canUndo and causesChange flags for the command.
  242.  
  243.     void SetPropertiesFromEvent(TAppleEvent* theEvent);
  244.     // Sets the properties of an object based on the data in the keyAEPropData parameter
  245.     // of the event.
  246.  
  247. //----------------------------------------------------------------------------------------
  248. // Attached Scripts
  249. //----------------------------------------------------------------------------------------
  250.  
  251. #if qAttachable
  252.  
  253.     Boolean HasOSAScript();
  254.         // Return TRUE if this object has a script attached.
  255.  
  256.     void FreeOSAScript();
  257.         // Throws out the script attached to this object.
  258.  
  259.     void SetOSAScript(const CAEDesc& scriptDesc);
  260.         // Attaches a script described in the scriptDesc
  261.  
  262.     void GetOSAScript(CAEDesc& scriptDesc,
  263.                               const CAEDesc& desiredType);
  264.         // Returns the script attached to this object as the desiredType.
  265.  
  266.     virtual Boolean HandleOSAEvent(CommandNumber aCommandNumber,
  267.                                    TAppleEvent* message,
  268.                                    TAppleEvent* reply);
  269.         // Gives an attached script a chance to handle an AppleEvent.
  270.         // Returns TRUE if the script handled the event.
  271.  
  272.     void IdleOSAScript();
  273.         // Gives an attached script idle time so its idle event handler can do some work.
  274.         // Respects the script's fNextScriptIdle so you can call it as often as you like.
  275.  
  276.     void ReadOSAScript(TStream* aStream);
  277.         // Reads an attached script from aStream.
  278.  
  279.     void WriteOSAScript(TStream* aStream, DescType asType);
  280.         // Writes an attached script to aStream.
  281.  
  282. #endif // qAttachable
  283.  
  284. };
  285.  
  286. //----------------------------------------------------------------------------------------
  287. // MDefaultScriptableObject: Definition of an object that responds to scripting appleevents.
  288. //----------------------------------------------------------------------------------------
  289.  
  290. class MDefaultScriptableObject : public MScriptableObject
  291. {
  292.     MA_DECLARE_CLASS;
  293.     
  294. public:
  295.     
  296.     MDefaultScriptableObject();
  297.     MDefaultScriptableObject(DescType myClassID);
  298.                                                     
  299.     virtual ~MDefaultScriptableObject();
  300.     
  301.     virtual void DoScriptCommand(CommandNumber        aCommandNumber,
  302.                                 TAppleEvent*         message,
  303.                                 TAppleEvent*         reply);    // Override
  304.     
  305.     inline Boolean IsRecordingOn();
  306.  
  307. protected:
  308.     
  309.     Boolean fRecording;
  310. };
  311.  
  312. inline Boolean MDefaultScriptableObject::IsRecordingOn()
  313. {
  314.     return fRecording;
  315. };
  316.  
  317. #endif // __USCRIPTABLEOBJECT__
  318.